.TH std::istream_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::istream_iterator \- std::istream_iterator

.SH Synopsis
   Defined in header <iterator>
   template< class T,

             class CharT = char,
             class Traits = std::char_traits<CharT>,
             class Distance = std::ptrdiff_t >                            \fI(until C++17)\fP
   class istream_iterator

       : public std::iterator<std::input_iterator_tag, T, Distance,
   const T*, const T&>
   template< class T,

             class CharT = char,
             class Traits = std::char_traits<CharT>,                      \fI(since C++17)\fP
             class Distance = std::ptrdiff_t >

   class istream_iterator;

   std::istream_iterator is a single-pass input iterator that reads successive objects
   of type T from the std::basic_istream object for which it was constructed, by
   calling the appropriate operator>>. The actual read operation is performed when the
   iterator is incremented, not when it is dereferenced. The first object is read when
   the iterator is constructed. Dereferencing only returns a copy of the most recently
   read object.

   The default-constructed std::istream_iterator is known as the end-of-stream
   iterator. When a valid std::istream_iterator reaches the end of the underlying
   stream, it becomes equal to the end-of-stream iterator. Dereferencing or
   incrementing it further invokes undefined behavior. An end-of-stream iterator
   remains in the end-of-stream state even if the underlying stream changes state.
   Absent a reassignment, it cannot become a non-end-of-stream iterator anymore.

   A typical implementation of std::istream_iterator holds two data members: a pointer
   to the associated std::basic_istream object and the most recently read value of type
   T.

   T must meet the DefaultConstructible, CopyConstructible, and CopyAssignable
   requirements.

.SH Member types

   Member type       Definition
   iterator_category std::input_iterator_tag
   value_type        T
   difference_type   Distance
   pointer           const T*
   reference         const T&
   char_type         CharT
   traits_type       Traits
   istream_type      std::basic_istream<CharT, Traits>

   Member types iterator_category, value_type, difference_type, pointer
   and reference are required to be obtained by inheriting from           \fI(until C++17)\fP
   std::iterator<std::input_iterator_tag, T, Distance, const T*, const
   T&>.

.SH Member functions

   constructor     constructs a new istream_iterator
                   \fI(public member function)\fP
   destructor      destructs an istream_iterator, including the cached value
                   \fI(public member function)\fP
   operator*       returns the current element
   operator->      \fI(public member function)\fP
   operator++      advances the iterator
   operator++(int) \fI(public member function)\fP

.SH Non-member functions

   operator==         compares two istream_iterators
   operator!=         \fI(function template)\fP
   (removed in C++20)

.SH Notes

   When reading characters, std::istream_iterator skips whitespace by default (unless
   disabled with std::noskipws or equivalent), while std::istreambuf_iterator does not.
   In addition, std::istreambuf_iterator is more efficient, since it avoids the
   overhead of constructing and destructing the sentry object once per character.

.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>
 #include <iterator>
 #include <numeric>
 #include <sstream>

 int main()
 {
     std::istringstream str("0.1 0.2 0.3 0.4");
     std::partial_sum(std::istream_iterator<double>(str),
                      std::istream_iterator<double>(),
                      std::ostream_iterator<double>(std::cout, " "));

     std::istringstream str2("1 3 5 7 8 9 10");
     auto it = std::find_if(std::istream_iterator<int>(str2),
                            std::istream_iterator<int>(),
                            [](int i){ return i % 2 == 0; });

     if (it != std::istream_iterator<int>())
         std::cout << "\\nThe first even number is " << *it << ".\\n";
     //" 9 10" left in the stream
 }

.SH Output:

 0.1 0.3 0.6 1
 The first even number is 8.

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to           Behavior as published              Correct behavior
   P0738R2 C++98      the first read might be deferred to the   always performed in the
                      first dereference                         constructor

.SH See also

   ostream_iterator    output iterator that writes to std::basic_ostream
                       \fI(class template)\fP
   istreambuf_iterator input iterator that reads from std::basic_streambuf
                       \fI(class template)\fP

.SH Hidden category:
     * Pages with unreviewed LWG DR marker
